home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / c / bplus11.zip / BPLUS.DOC < prev    next >
Text File  |  1988-12-06  |  25KB  |  640 lines
  1. \033(s10H
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                                THE B-PLUS PROGRAM
  8.                          A B-TREE INDEXING FILE MODULE
  9.                                FOR C PROGRAMMERS
  10.                                        by
  11.                              Hunter and Associates
  12.  
  13.  
  14.  
  15.               B-PLUS is a versatile, carefully designed module for C
  16.          programmers who need a fast, efficient program for indexing
  17.          data files.  B-PLUS allows data records to be retrieved based
  18.          on a key value without regard to their position in the data
  19.          file.  The data records can also be accessed in sequential
  20.          order in either a forward and reverse direction.
  21.  
  22.               The B-PLUS Program Module is based on the famous and
  23.          widely used b-tree algorithm and has a number of useful
  24.          extensions which are not found in many programs of this type.
  25.          Some of its features are the following:
  26.  
  27.               - Variable length keys are allowed
  28.  
  29.               - File size limited only by DOS or by disk space
  30.  
  31.               - All functions are non-recursive so very little stack
  32.                 space is required
  33.  
  34.               - The most recently used key values are stored in a
  35.                 cache buffer in main memory for fast access
  36.  
  37.               - Duplicate keys are allowed
  38.  
  39.               The B-PLUS program has been tested using the Microsoft C
  40.          Compilers, Versions 4.0, 4.5 (OS2 Beta release), 5.0 and the
  41.          Borland Turbo C Compiler Version 1.0.  The compiled object
  42.          file is less than 9.4K bytes in length for these compilers.
  43.          See the instructions at the end of this user's guide for a
  44.          special note regarding Microsoft C Version 5.0 and Quick C.
  45.  
  46.               Version 1.1 has several new features that were not in
  47.          Version 1.0.  The next_key and prev_key routines can now be
  48.          called immediately after adding or deleting an index key.  It
  49.          is no longer necessary to "reset" the index file with a
  50.          find_key or locate_key function call after adding or deleting
  51.          keys.  Several minor bugs that were discovered in Version 1.0
  52.          have been corrected in Version 1.1.
  53.  
  54.  
  55.          LICENSE AND REGISTRATION
  56.  
  57.               B-PLUS is distributed as a "share ware" program.  Please
  58.          help us get it known by giving unmodified copies of the
  59.  
  60.  
  61.          HUNTER AND ASSOCIATES            B-PLUS FILE INDEXING PROGRAM
  62.          -------------------------------------------------------------
  63.  
  64.  
  65.          program and documentation to other programmers who may find
  66.          B-PLUS useful.
  67.  
  68.               B-PLUS is copyright (C) 1987 by Hunter and Associates.
  69.          It is not public domain or free software.  Non-registered
  70.          users are granted a limited license to use B-PLUS on a trial
  71.          basis for determining whether or not it is suitable for their
  72.          needs.  Registration permits the use of B-PLUS on one CPU and
  73.          allows the use of the compiled B-PLUS modules in programs for
  74.          general sale and/or distribution.
  75.  
  76.               The registration fee is $25 or $35.  Users who pay the
  77.          $35 fee will be sent a disk containing a fully commented
  78.          listing of the latest source code, the user documentation,
  79.          and a number of useful sample programs.  Users who pay the
  80.          $25 fee are not sent a new disk but are included in the
  81.          mailing list for announcements about both current and future
  82.          products.  Your prompt registration of your copy of the B-
  83.          PLUS program is appreciated.
  84.  
  85.               A trial disk with supporting documentation is available
  86.          directly from Hunter and Associates for $10.
  87.  
  88.               Register your usage of B-PLUS by sending the registra-
  89.          tion fee to:
  90.  
  91.                         Hunter and Associates
  92.                         7050 NW Zinfandel Lane
  93.                         Corvallis, OR  97330
  94.                         Telephone: (503) 745-7186
  95.  
  96.          Your comments regarding the B-PLUS program or any suggestions
  97.          you have for extensions or for other programs that would be
  98.          useful to you are welcomed.
  99.  
  100.               Hunter and Associates makes no warranties whatsoever
  101.          regarding the B-PLUS computer programs or the supporting
  102.          documentation.
  103.  
  104.  
  105.          USING B-PLUS IN YOUR PROGRAMS
  106.  
  107.               The B-PLUS File Indexing Module contains twelve
  108.          functions that handle the retrieval of data records by key
  109.          value.  The keys that are used to locate records are null
  110.          terminated strings.  The data structures and constants that
  111.          are used are defined in the header file bplus.h.
  112.  
  113.               If the data record field that you want to use as a key
  114.          contains numeric data, you can use one of the library
  115.  
  116.                                    Page 2
  117.  
  118.  
  119.          HUNTER AND ASSOCIATES            B-PLUS FILE INDEXING PROGRAM
  120.          -------------------------------------------------------------
  121.  
  122.  
  123.          conversion routines (fcvt, evct, sprintf) to convert the data
  124.          to string format.
  125.  
  126.               The connection between a key and its reference is
  127.          formalized as a structure of type ENTRY.  This structure
  128.          contains three elements:
  129.  
  130.          typedef struct
  131.            {
  132.              RECPOS   idxptr;         /* long pointer to next index
  133.                                          level                      */
  134.              RECPOS   recptr;         /* long pointer to the file
  135.                                          position of data record    */
  136.              char     key[MAXKEY];    /* with this key value        */
  137.            } ENTRY;
  138.  
  139.               The application program uses only the recptr and key[]
  140.          fields.  The idxptr is used and maintained by the B-PLUS
  141.          modules.
  142.  
  143.               A variable of type IX_DESC is declared for each open
  144.          index file.  See the header file bplus.h if you are
  145.          interested in the elements of this structure.  ENTRY and
  146.          IX_DESC are the only two data types that are normally used by
  147.          application programs.
  148.  
  149.               Here is a sample program stub which calls the open_index
  150.          and find_index subroutines.
  151.  
  152.  
  153.          Example:
  154.  
  155.            #include "bplus.h"
  156.            main()
  157.              {
  158.                 ENTRY    e;
  159.                 IX_DESC  names;
  160.  
  161.                 /* open index file called NAMES.IDX */
  162.  
  163.                 open_index("NAMES.IDX", &names, 0);
  164.  
  165.                 /* find an index record for John Smith */
  166.  
  167.                 strcpy(e.key, "SMITH JOHN");
  168.                 if(find_key(&e, &names))
  169.                   printf("Data record address is %ld", e.recptr);
  170.                 else
  171.                   printf("Cannot find record for that key");
  172.               }
  173.  
  174.                                    Page 3
  175.  
  176.  
  177.          HUNTER AND ASSOCIATES            B-PLUS FILE INDEXING PROGRAM
  178.          -------------------------------------------------------------
  179.  
  180.  
  181.          Each of the twelve subroutines is now described.
  182.  
  183.          int cdecl open_index(name, pix, dup);
  184.  
  185.               char *name;         File path name
  186.               IX_DESC *pix;       Pointer to index file variable
  187.               int dup;            0 - no duplicate keys allowed
  188.                                   1 - allow duplicate keys
  189.  
  190.               Description:  The open_index function is used to open
  191.               and initialize an existing index file specified by name
  192.               and prepares the file for subsequent reading or writing.
  193.               The file structure variable pix is defined in the
  194.               application program.  Duplicate keys are allowed or not
  195.               allowed depending on whether dup has the value of 0 or
  196.               1.  The open_index function returns the value IX_OK (1)
  197.               if the file is opened successfully.  If the file cannot
  198.               be opened, an error message is displayed and the program
  199.               is aborted.
  200.  
  201.  
  202.  
  203.